Build a KiteGeometry SystemDefinition from KPS3 and KPS4 and carry it in the log - #327

Depends-On: OpenSourceAWE/KiteGeometry.jl release after v0.1.0

Until now a KPS3 or KPS4 run described its system only through a segment count and a few settings. Nothing that reads a system definition could draw it, KiteViewers included. Now the model can describe itself as a KiteGeometry system definition: its points, the springs it integrates as segments, one tether and one winch. That definition can be saved in the log, so a viewer reading the log gets the topology the run actually integrated. KiteGeometry is re-exported, as KiteModels already does for KitePodModels, WinchModels and AtmosphericModels.

integrator = init!(kps4)
definition = system_definition(kps4)         # new
# ... simulate and log! ...
save_log(logger, definition, "sim_log")      # stores the definition in the log
KiteGeometry.definition(load_log("sim_log")) # reads it back

What the definition holds:

• Points. One point per model point, named "1" upwards. Point 1 is the winch and is static.
• Segments. For KPS4 these are the model's own spring list: 6 tether springs and 9 bridle springs, with their endpoints, rest lengths and nominal stiffness. The connectivity is therefore what the model integrates, not a second copy of the spring table. The bridle springs are massless, as KPS4 treats them, and keep the line diameter used for their drag. KPS3 has no spring list, so its segments join neighbouring points.
• Masses. For KPS4 the KCU mass sits on the KCU point and the kite mass on points A–D. For KPS3 both sit on the last point. Tether mass comes from the segments' density and diameter.
• Tether and winch. The tether runs from the winch to the KCU. Gear ratio and drum radius come from the settings.
• Pose and stiffness. The pose is wherever the points are when the definition is built, so build it right after init!. The stiffness is the nominal value. The model only scales it below nominal during a start-up ramp.
• Log format. Saving and reading the definition in a log are KiteGeometry's, so every model that builds a definition logs it the same way. The log stores it as JSON under the key topology. The definition carries its connectivity checksum, so a reader can tell when a log's states were recorded against a different topology.

This needs OpenSourceAWE/KiteGeometry.jl#50, which adds the log methods. Until a KiteGeometry release carries it, this branch's tests fail in CI against KiteGeometry 0.1.0. Once it is released, the KiteGeometry compat entry here rises to that version, with a minimal manifest resolve.

Where I'd push back:

• The example is not literally unchanged. The torque-control reel-out example changes two lines: it builds the definition after init! and passes it to save_log. Its logger never sees the model, and KiteUtils' logger has nowhere to keep metadata, so an untouched script cannot carry the definition without global state. The simulation itself is unchanged.
• The issue says this repo writes aero_force_b and tether_induced_force every step. It writes neither, so the KiteUtils state rename has nothing to change here.
• The metadata's schema version comes from a constant KiteGeometry does not export. KiteGeometry's metadata type has only a positional constructor with no defaults. A keyword constructor with defaults would belong in KiteGeometry: Metadata has no keyword constructor, and AWESIO_VERSION is not public KiteGeometry.jl#49.

Dependencies: KiteGeometry 0.1.0, from the General registry. Both manifests come from a minimal resolve that started from main's. They gain the KiteGeometry entry and its JSON dependency. The 1.13 resolve ran under Julia 1.13.0, while main's 1.13 manifest was written under 1.13.1, so it also records julia_version 1.13.0 and the LibSSH2_jll that ships with 1.13.0.

Verification

• Reproduced first: n/a, new feature.
• test/test-system-definition.jl: the log testset errored against KiteGeometry 0.1.0 (MethodError, since no save_log takes a definition there) and passes against the KiteGeometry branch. 16/16 across 3 testsets (juliaserver, Julia 1.13.0, test project).
• Acceptance against the KiteGeometry branch: examples/reel_out_4p_torque_control.jl runs to the end and logs 1800 rows of 11 points. KiteGeometry.definition on the loaded log gives 11 points (length(kps4.pos) is 11) and 15 segments whose endpoints equal the model's springs (true). The tether is segments 1–6, the drum radius 0.1615, and unit_stiffness matches at stiffness_factor 1.0.
• test/test-aqua.jl 9/9 · docs build clean · up to date with main (b84950a, DSP 0.8.6 manifests).
• GitHub CI: expected red until the KiteGeometry release. The commit before this change passed tests, docs, REUSE lint and link check.
• REUSE lint: not run locally (no reuse on the box).
• Benchmark: n/a, not on the step path.
• Risk: a definition built after the run has started records the current pose, not the initial one. The docstring says to build it after init!.

Opened elsewhere

• Pull request: Save a KiteUtils log with its system definition, and read it back from the loaded log KiteGeometry.jl#50

Opened by 1-Bort-1, an AI agent working for @1-Bart-1.
Closes #322 · task KiteModels.jl-322